JavaScript Temporal Takvim Dönüşümü: Takvimler Arası Tarih Eşlemesinde Uzmanlaşma

Dünya sadece Gregoryen takvimine göre işlemiyor. Küresel olarak genişleyen işletmelerin, her biri belirli takvim sistemlerine bağlı çeşitli kültürel ve dini kutlamaları dikkate alması gerekiyor. JavaScript'in modern Temporal API'si, bu karmaşıklıkları yönetmek için güçlü araçlar sunarak geliştiricilerin takvimler arasında sorunsuzca tarih eşlemesi yapmasına ve doğru zamanlama, hesaplama ve veri sunumu sağlamasına olanak tanır. Bu kapsamlı kılavuz, Temporal API'sinin takvim dönüştürme yeteneklerini inceliyor ve küresel farkındalığa sahip uygulamalar oluşturmak için pratik örnekler ve en iyi uygulamaları sunuyor.

Takvimler Arası Tarih Eşlemesi İhtiyacını Anlamak

Geleneksel JavaScript `Date` nesneleri, Gregoryen olmayan takvimleri yönetme konusunda sınırlamalara sahiptir. Temporal API, çeşitli takvim sistemleriyle çalışmak için standartlaştırılmış ve sağlam bir yol sunarak bu sorunu çözer. Şu senaryoları düşünün:

• Uluslararası toplantıları planlama: Gregoryen takvimine göre planlanmış bir etkinliğin İslami (Hicri) veya İbrani takvimindeki eşdeğer tarihini doğru bir şekilde belirlemek, dini bayramlara ve kültürel hassasiyetlere saygı göstermek için çok önemlidir.
• Farklı bölgelerde kredi faizini hesaplama: Bazı finansal kurumlar faiz hesaplamaları için belirli takvimler kullanır. Temporal, bu sistemlerde hassas tarih aritmetiği yapılmasına olanak tanır.
• Tarihleri kullanıcı tercihli formatlarda görüntüleme: Tarih gösterimlerini kullanıcının yerel ayarlarına ve takvim tercihine göre uyarlamak, özellikle çeşitli popülasyonları hedefleyen uygulamalar için kullanıcı deneyimini artırır.
• Tarihsel veri analizi: Tarihsel veri setleriyle çalışırken, eski veya daha az yaygın takvimlerde kaydedilmiş tarihleri anlamak ve dönüştürmek, doğru yorumlama için gerekli hale gelir.

Temporal API ve Takvimlere Giriş

Artık modern JavaScript ortamlarında yaygın olarak desteklenen Temporal API, tarihler, saatler ve saat dilimleriyle çalışmak için daha sezgisel ve güçlü bir yol sunar. Özünde, `Temporal.Calendar` nesnesi belirli bir takvim sistemini temsil eder. Temporal.PlainDate, Temporal.PlainDateTime ve diğer Temporal türleri bir `Temporal.Calendar` örneğiyle ilişkilendirilebilir.

Temporal API, bu yazının yazıldığı sırada şu takvimleri desteklemektedir:

• `iso8601` (Gregoryen - varsayılan)
• `gregory` (`iso8601` için bir takma ad)
• `islamic`
• `islamic-umalqura`
• `islamic-tbla`
• `islamic-rgsa`
• `islamic-civil`
• `hebrew`
• `buddhist`
• `roc` (Çin Cumhuriyeti)
• `japanese`
• `persian`

Gelecekteki sürümler daha fazla takvim sunabilir veya özel takvim uygulamalarına izin verebilir.

Temporal.PlainDate ile Temel Takvim Dönüşümü

`Temporal.PlainDate` nesnesi, saat dilimi olmayan bir tarihi temsil eder. Belirli bir takvimle ilişkilendirilmiş bir `Temporal.PlainDate` oluşturabilirsiniz:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = Temporal.PlainDate.from({ year: 1445, month: 6, day: 8, calendar: islamicCalendar });

console.log(gregorianDate.toString()); // Çıktı: 2024-01-20
console.log(islamicDate.toString());   // Çıktı: 1445-06-08[u-ca=islamic]

`toString()` metodu, tarihi bir takvim ek açıklaması olan `[u-ca=islamic]` ile birlikte çıkaracaktır. Bu, tarihin İslami takvimle ilişkili olduğunu gösterir.

Takvimler Arasında Dönüşüm Yapma

Takvimler arasında dönüştürmenin anahtarı, her takvimle ilişkili `Temporal.PlainDate` nesneleri oluşturmak ve ardından ilgili tarih bileşenlerini çıkarmaktır. İşte bir Gregoryen tarihini İslami takvimdeki eşdeğerine nasıl dönüştüreceğiniz:

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');

// İslami takvimdeki tarih bileşenlerini çıkar
const islamicYear = gregorianDate.toPlainDate(islamicCalendar).year;
const islamicMonth = gregorianDate.toPlainDate(islamicCalendar).month;
const islamicDay = gregorianDate.toPlainDate(islamicCalendar).day;

console.log(`Gregoryen: ${gregorianDate.toString()}`);
console.log(`İslami: ${islamicYear}-${islamicMonth}-${islamicDay}`); // Çıktı: İslami: 1445-6-8

Bu örneği ayrıntılı olarak inceleyelim:

1. Bir `Temporal.PlainDate` nesnesi olarak temsil edilen bir `gregorianDate` ile başlıyoruz.
2. `Temporal.Calendar.from('islamic')` kullanarak bir `islamicCalendar` nesnesi oluşturuyoruz.
3. Temel dönüşüm `gregorianDate.toPlainDate(islamicCalendar)` ile gerçekleşir. Bu, aynı zaman noktasını temsil eden ancak şimdi İslami takvimle ilişkilendirilmiş yeni bir `Temporal.PlainDate` nesnesi oluşturur.
4. Dönüştürülmüş `Temporal.PlainDate` nesnesinden `year`, `month` ve `day` bileşenlerini çıkarıyoruz.

Bu deseni, Temporal API tarafından desteklenen herhangi iki takvim arasında dönüştürme yapmak için uyarlayabilirsiniz.

İleri Düzey Takvim Yönetimi: İslami Takvimler

İslami takvimin birkaç varyasyonu vardır. Temporal API bunları destekler:

• `islamic`: Genel bir İslami takvim (uygulama değişebilir).
• `islamic-umalqura`: Suudi Arabistan'ın Ümmü'l-Kurra takvimine dayanır.
• `islamic-tbla`: Tablolu hesaplamaya dayanır.
• `islamic-rgsa`: Mısır'daki Diyanet Genel Sekreterliği'ne dayanır.
• `islamic-civil`: İslami takvimin tamamen aritmetik bir versiyonu, öncelikle hesaplamalar için kullanılır.

İslami takvimle çalışırken, kullanım durumunuz için hangi varyasyonun uygun olduğunu anlamak çok önemlidir. Örneğin, Suudi Arabistan'daki dini kutlamalar için muhtemelen `islamic-umalqura` kullanmak istersiniz. Finansal hesaplamalar için, öngörülebilir doğası nedeniyle `islamic-civil` daha uygun olabilir.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const islamicUmalquraCalendar = Temporal.Calendar.from('islamic-umalqura');
const islamicCivilCalendar = Temporal.Calendar.from('islamic-civil');

const islamicUmalquraDate = gregorianDate.toPlainDate(islamicUmalquraCalendar);
const islamicCivilDate = gregorianDate.toPlainDate(islamicCivilCalendar);

console.log(`Gregoryen: ${gregorianDate.toString()}`);
console.log(`İslami (Ümmü'l-Kurra): ${islamicUmalquraDate.year}-${islamicUmalquraDate.month}-${islamicUmalquraDate.day}`);
console.log(`İslami (Sivil): ${islamicCivilDate.year}-${islamicCivilDate.month}-${islamicCivilDate.day}`);

İslami Takvimler İçin Önemli Hususlar:

• İslami takvimde yeni bir ayın başlangıcı, yeni hilalin görülmesine dayanır. `islamic-umalqura` takvimi, Suudi Arabistan'daki gerçek ay gözlemleriyle uyumlu olmayı hedefler, ancak yine de tutarsızlıklar meydana gelebilir.
• `islamic-civil` takvimi matematiksel bir yaklaşımdır ve gerçek ay gözlemlerini yansıtmaz.
• İslami bayramların doğru tarihleri için her zaman ilgili dini yetkililere veya güvenilir kaynaklara danışın.

İbrani Takvimi ile Çalışma

İbrani takvimi, Yahudi dini kutlamaları için kullanılan ve İsrail'de resmi bir takvim olan bir ay-güneş takvimidir. Mevsimlerle uyumlu kalmak için artık aylar içerir.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');

const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

console.log(`Gregoryen: ${gregorianDate.toString()}`);
console.log(`İbrani: ${hebrewDate.year}-${hebrewDate.month}-${hebrewDate.day}`);

İbrani Takvimi ve Temporal'in Temel Özellikleri:

• Artık aylar, Temporal API tarafından otomatik olarak yönetilir. Artık yılları belirlemek veya ekstra aylar eklemek için özel mantık uygulamanız gerekmez.
• Yıl numaralandırması, geleneksel Yahudi döneminden (dünyanın yaratılışı) başlar.
• İbrani takvimi ay adları, Gregoryen takviminden farklıdır. Bu ay adlarına uluslararasılaştırma (i18n) kütüphaneleri veya özel eşlemeler aracılığıyla erişebilirsiniz.

Budist, ROC, Japon ve Fars Takvimlerini Yönetme

Temporal API, her birinin kendine özgü özellikleri olan diğer takvimleri de destekler. İşte bazı hususlar:

• Budist Takvimi: Budist takvimi, birçok Güneydoğu Asya ülkesinde kullanılan bir ay-güneş takvimidir. Yıl numaralandırması genellikle Buda'nın ölümünden başlar.
• ROC Takvimi (Çin Cumhuriyeti): Bu takvim Tayvan'da kullanılır ve yılları 1912'de Çin Cumhuriyeti'nin kuruluşundan itibaren numaralandırır.
• Japon Takvimi: Japon takvimi Gregoryen takvimine dayanır ancak yılları belirtmek için Japon dönem adlarını (nengō) kullanır.
• Fars Takvimi: Fars takvimi, öncelikle İran ve Afganistan'da kullanılan bir güneş takvimidir.

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const buddhistCalendar = Temporal.Calendar.from('buddhist');
const rocCalendar = Temporal.Calendar.from('roc');
const japaneseCalendar = Temporal.Calendar.from('japanese');
const persianCalendar = Temporal.Calendar.from('persian');

const buddhistDate = gregorianDate.toPlainDate(buddhistCalendar);
const rocDate = gregorianDate.toPlainDate(rocCalendar);
const japaneseDate = gregorianDate.toPlainDate(japaneseCalendar);
const persianDate = gregorianDate.toPlainDate(persianCalendar);

console.log(`Gregoryen: ${gregorianDate.toString()}`);
console.log(`Budist: ${buddhistDate.year}-${buddhistDate.month}-${buddhistDate.day}`);
console.log(`ROC: ${rocDate.year}-${rocDate.month}-${rocDate.day}`);
console.log(`Japon: ${japaneseDate.year}-${japaneseDate.month}-${japaneseDate.day}`);
console.log(`Fars: ${persianDate.year}-${persianDate.month}-${persianDate.day}`);

Bu takvimleri kullanırken, özel başlangıç dönemlerinin (başlangıç yılı) ve tarih gösterimiyle ilgili kültürel nüansların farkında olun.

Temporal.Now ve Takvim Hususları

`Temporal.Now` geçerli tarih ve saati almak için kullanılabilirken, varsayılan olarak ISO 8601 takvimindeki geçerli tarih ve saati döndürdüğünü anlamak önemlidir. Geçerli tarihi farklı bir takvimde ihtiyacınız varsa, onu dönüştürmeniz gerekir:

const islamicCalendar = Temporal.Calendar.from('islamic');
const now = Temporal.Now.plainDateISO(); // ISO 8601 takviminde geçerli tarih
const islamicNow = now.toPlainDate(islamicCalendar);

console.log(`Geçerli Gregoryen Tarihi: ${now.toString()}`);
console.log(`Geçerli İslami Tarih: ${islamicNow.year}-${islamicNow.month}-${islamicNow.day}`);

Tarih Biçimlendirme ve Uluslararasılaştırma (i18n)

Tarihleri dönüştürmek denklemin sadece bir parçasıdır. Bunları ayrıca görüntüleme için doğru şekilde biçimlendirmeniz gerekir. JavaScript'in `Intl.DateTimeFormat` API'si güçlü uluslararasılaştırma yetenekleri sağlar. Bunu, ilişkili takvimi dikkate alarak tarihleri yerel ayarların farkında bir şekilde biçimlendirmek için Temporal API ile birlikte kullanabilirsiniz.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

const formatter = new Intl.DateTimeFormat('ar-SA-u-ca-islamic', { // Arapça (Suudi Arabistan) İslami takvimle
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(islamicDate)); // Örnek çıktı: ٢٠ رجب، ١٤٤٥ هـ

Kodu analiz edelim:

• `'ar-SA-u-ca-islamic'` yerel ayar dizesidir. `ar-SA` Arapça (Suudi Arabistan) belirtir ve `u-ca-islamic` açıkça İslami takvimi talep eder.
• `Intl.DateTimeFormat` seçenekleri, tarihin nasıl biçimlendirileceğini kontrol eder (yıl, ay, gün).
• `format()` metodu bir `Temporal.PlainDate` nesnesi (bu durumda `islamicDate`) alır ve belirtilen yerel ayar ve takvime göre biçimlendirilmiş bir dize döndürür.

Yerel ayar dizesini ve biçimlendirme seçeneklerini özel ihtiyaçlarınıza uyacak şekilde uyarlayabilirsiniz. Örneğin, tarihi İbranice biçimlendirmek için:

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');
const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

const formatter = new Intl.DateTimeFormat('he-IL-u-ca-hebrew', { // İbranice (İsrail) İbrani takvimiyle
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(hebrewDate));

Etkili Tarih Biçimlendirme İpuçları:

• Kullanıcının tercih ettiği dili ve bölgeyi doğru yansıtan yerel ayar dizeleri kullanın.
• Bağlama uygun biçimlendirme seçenekleri seçin (örneğin, kompakt gösterimler için kısa tarih formatları, ayrıntılı sunumlar için uzun tarih formatları).
• Doğruluk ve okunabilirlik sağlamak için biçimlendirmenizi farklı yerel ayarlarda test edin.

Takvimler Arasında Tarih Aritmetiği Yapma

Temporal API, tarih aritmetiğinde mükemmeldir. Gregoryen olmayan takvimlerle çalışırken bile bir `Temporal.PlainDate` nesnesine gün, ay veya yıl ekleyebilir veya çıkarabilirsiniz.

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

// İslami tarihe 30 gün ekle
const futureIslamicDate = islamicDate.add({ days: 30 });

console.log(`Orijinal İslami Tarih: ${islamicDate.year}-${islamicDate.month}-${islamicDate.day}`);
console.log(`İslami Tarih + 30 gün: ${futureIslamicDate.year}-${futureIslamicDate.month}-${futureIslamicDate.day}`);

// Gelecekteki İslami tarihi tekrar Gregoryen'e dönüştür
const futureGregorianDate = futureIslamicDate.toPlainDate('iso8601');
console.log(`Eşdeğer Gregoryen Tarihi: ${futureGregorianDate.toString()}`);

Tarih Aritmetiği için Temel Hususlar:

• `add()` ve `subtract()` metodları yeni `Temporal.PlainDate` nesneleri döndürür; orijinal nesneyi değiştirmezler.
• Ay veya yıl eklerken veya çıkarırken, Temporal API artık yıllar ve ay uzunlukları için takvime özgü kuralları yönetir.
• Aritmetik yaparken potansiyel tarih taşmalarına veya eksiklerine dikkat edin. Temporal API genellikle tarihi takvim içindeki en yakın geçerli tarihe ayarlar.

Belirsiz Tarihleri Yönetme

Bazı durumlarda, bir tarih takvimler arasında dönüştürülürken belirsiz olabilir. Bu, belirli bir tarihin hedef takvimde mevcut olmadığı veya hedef takvimdeki birden fazla tarihin kaynak tarihe karşılık gelebileceği durumlarda meydana gelebilir. Temporal bu durumları zarif bir şekilde yönetir, genellikle en yakın geçerli tarihi döndürerek.

Örneğin, bir Gregoryen ayının sonuna yakın bir Gregoryen tarihini, karşılık gelen İslami ayın daha kısa olabileceği İslami takvime dönüştürmeyi düşünün. Temporal, sonuçtaki İslami tarihi otomatik olarak o ayın son gününe ayarlayacaktır.

Hata Yönetimi ve Doğrulama

Temporal API sağlam olsa da, beklenmedik davranışları önlemek için uygun hata yönetimi ve doğrulama uygulamak önemlidir. İşte dikkate alınması gereken bazı yaygın senaryolar:

• Geçersiz Takvim Adları: `Temporal.Calendar.from()`'a geçersiz bir takvim adı sağlarsanız, bir `RangeError` fırlatır. Bu hatayı yakalayın ve kullanıcı dostu bir mesaj sağlayın.
• Geçersiz Tarih Formatları: Geçersiz bir tarih dizesinden bir `Temporal.PlainDate` oluşturmaya çalışırsanız, bir `RangeError` fırlatır. Tarih dizelerini `Temporal.PlainDate.from()`'a geçirmeden önce doğrulayın.
• Desteklenmeyen İşlemler: Bazı takvime özgü işlemler Temporal API tarafından desteklenmeyebilir. Kullandığınız belirli takvim için belgeleri kontrol edin.

Takvimler Arası Tarih Eşlemesi İçin En İyi Uygulamalar

Takvimler arası tarih eşlemesiyle çalışırken doğruluk ve sürdürülebilirlik sağlamak için şu en iyi uygulamaları izleyin:

• Temporal API'yi Kullanın: Temporal API, takvim dönüşümlerini yönetmek için standartlaştırılmış ve sağlam bir yol sağlar. Bu amaçla eski JavaScript `Date` nesnelerini kullanmaktan kaçının.
• Takvimleri Açıkça Belirtin: `Temporal.PlainDate` nesneleri oluştururken her zaman takvimi açıkça belirtin. Bu, belirsizliği önler ve doğru takvim kurallarının uygulanmasını sağlar.
• Doğru İslami Takvim Varyasyonunu Seçin: Çeşitli İslami takvim uygulamaları arasındaki farkları anlayın ve kullanım durumunuz için en uygun olanı seçin.
• Uluslararasılaştırma (i18n) Kullanın: Tarihleri yerel ayarların farkında bir şekilde biçimlendirmek için `Intl.DateTimeFormat` API'sinden yararlanın.
• Hata Yönetimi Uygulayın: Geçersiz takvim adlarını, tarih formatlarını ve diğer potansiyel sorunları yakalamak için sağlam hata yönetimi uygulayın.
• Kapsamlı Test Edin: Doğruluk ve uyumluluk sağlamak için kodunuzu çeşitli tarihler ve yerel ayarlarla test edin.
• Güncel Kalın: Temporal API hala gelişmektedir. En son spesifikasyonlar ve tarayıcı uygulamalarıyla güncel kalın.

Sonuç

JavaScript'in Temporal API'si, tarihleri ve takvimleri nasıl yönettiğimizi devrim niteliğinde değiştirerek takvimler arası tarih eşlemesi yapmak için güçlü ve standartlaştırılmış bir yol sağlar. Farklı takvim sistemlerinin nüanslarını anlayarak ve Temporal API'yi etkili bir şekilde kullanarak, geliştiriciler çeşitli kültürel ve dini ihtiyaçlara hitap eden küresel farkındalığa sahip uygulamalar oluşturabilirler. Projelerinizde daha kapsayıcı ve doğru tarih yönetimi çözümleri oluşturmak için Temporal API'yi benimseyin.

Bu kılavuz, JavaScript Temporal API ile takvim dönüşümüne kapsamlı bir genel bakış sunmuştur. En güncel bilgiler ve ayrıntılı spesifikasyonlar için resmi Temporal API belgelerine başvurmayı unutmayın.